﻿/*  ------------------------------------------------------------------------
	 NQ Common Services Library
	 
	 Homepage: http://www.awzhome.de/
	 ------------------------------------------------------------------------
	 
	 The contents of this file are subject to the Mozilla Public License
	 Version 1.1 (the "License"); you may not use this file except in
	 compliance with the License. You may obtain a copy of the License at
	 http://www.mozilla.org/MPL/
	 
	 Software distributed under the License is distributed on an "AS IS"
	 basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
	 License for the specific language governing rights and limitations
	 under the License.
	
	 The Original Code is code of NQ Common Services Library.

	 The Initial Developer of the Original Code is Andreas Weizel.
	 Portions created by the Initial Developer are
	 Copyright (C) 2011-2012 Andreas Weizel. All Rights Reserved.
	 
	 Contributor(s): (none)
	 
	 Alternatively, the contents of this file may be used under the terms
	 of the GNU General Public License Version 2.0 or later (the "GPL"),
	 or the GNU Lesser General Public License Version 2.1 or later (the
	 "LGPL"), in which case the provisions of the GPL or the LGPL are
	 applicable instead of those above. If you wish to allow use of your
	 version of this file only under the terms of the GPL or the LGPL and
	 not to allow others to use your version of this file under the MPL,
	 indicate your decision by deleting the provisions above and replace
	 them with the notice and other provisions required by the GPL or the
	 LGPL. If you do not delete the provisions above, a recipient may use
	 your version of this file under the terms of any of the MPL, the GPL
	 or the LGPL.
	 ------------------------------------------------------------------------
*/

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace AWZhome.NQ.CommonServices
{
	/// <summary>
	/// Interface for services managing the application's configuration.
	/// </summary>
	/// <remarks>
	/// Usually the service loads the configuration into an internal cache in 
	/// <see cref="AWZhome.NQ.CommonServices.IConfigManager.LoadConfiguration">LoadConfiguration</see>
	/// method and uses it for reading and writing operations. In 
	/// <see cref="AWZhome.NQ.CommonServices.IConfigManager.SaveConfiguration">SaveConfiguration</see>
	/// method that is called when the application ends the service saves the contents of the cache
	/// back to disk.
	/// </remarks>
	public interface IConfigManager
	{
		/// <summary>
		/// Returns the path where the NQ system saves the user's settings.
		/// </summary>
		string UserAppDataPath
		{
			get;
		}

		/// <summary>
		/// Returns the path where the NQ systems saves common settings.
		/// </summary>
		/// <remarks>
		/// In the current version of NQ Common Services this path is not used.
		/// </remarks>
		string CommonAppDataPath
		{
			get;
		}

		/// <summary>
		/// Returns list of all available category names.
		/// </summary>
		/// <returns>Array of category names.</returns>
		string[] GetCategoryList();

		/// <summary>
		/// Returns the list of all group identifiers in a category.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <returns>Array of group identifiers.</returns>
		string[] GetGroupList(string category);

		/// <summary>
		/// Returns the list of all setting names defined in a group.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Group identifier.</param>
		/// <param name="includeValueSettings">If <c>true</c>, single-value settings are included.</param>
		/// <param name="includeListSettings">If <c>true</c>, list settings are included.</param>
		/// <returns>Array of all setting names.</returns>
		string[] GetSettingList(string category, string group, bool includeValueSettings, bool includeListSettings);

		/// <summary>
		/// Returns the value of a setting.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Identifier of setting group in category.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <returns>A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</returns>
		ConfigData GetSetting(string category, string group, string settingName);

		/// <summary>
		/// Returns a list setting.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Identifier of setting group in category.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <returns>A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</returns>
		System.Collections.Generic.IList<ConfigData> GetListSetting(string category, string group, string settingName);

		/// <summary>
		/// Sets the value of a setting.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Identifier of setting group in category.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="data">A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</param>
		/// <param name="userSetting">Sets if the setting should be written to the user-specific configuration.</param>
		/// <returns><c>True</c>, if the value could be set successfully.</returns>
		bool SetSetting(string category, string group, string settingName, ConfigData data, bool userSetting);

		/// <summary>
		/// Sets a list setting.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Identifier of setting group in category.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="data">A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</param>
		/// <param name="userSetting">Sets if the setting should be written to the user-specific configuration.</param>
		/// <returns><c>True</c>, if the value could be set successfully.</returns>
		bool SetListSetting(string category, string group, string settingName, System.Collections.Generic.IList<ConfigData> data, bool userSetting);

		/// <summary>
		/// Removes a setting from configuration.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Identifier of setting group in category.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="userSetting">Sets if the setting should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveSetting(string category, string group, string settingName, bool userSetting);

		/// <summary>
		/// Removes list setting from configuration.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Identifier of setting group in category.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="userSetting">Sets if the setting should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveListSetting(string category, string group, string settingName, bool userSetting);

		/// <summary>
		/// Renames a group keeping all settings it contains.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="oldGroupName">Old name of the group.</param>
		/// <param name="newGroupName">New name of the group</param>
		/// <param name="userSetting">Sets if the setting should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c>, if renaming was successful, <c>false</c> otherwise.</returns>
		bool RenameGroup(string category, string oldGroupName, string newGroupName, bool userSetting);

		/// <summary>
		/// Removes a group with its settings from configuration.
		/// </summary>
		/// <param name="category">Setting category.</param>
		/// <param name="group">Group to remove.</param>
		/// <param name="userSetting">Sets if the setting should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c> if successful, <c>false</c> otherwise.</returns>
		bool RemoveGroup(string category, string group, bool userSetting);

		/// <summary>
		/// Loads the configuration from the setting file to the service's internal cache.
		/// </summary>
		/// <remarks>
		/// This method is usually called externally when application starts.
		/// </remarks>
		void LoadConfiguration();

		/// <summary>
		/// Writes the configuration from the service's internal cache to the setting file.
		/// </summary>
		/// <remarks>
		/// The service is responsible for calling this method when it's destroyed.
		/// </remarks>
		void SaveConfiguration();

		/// <summary>
		/// Sets the configuration name used for file and directory names of the configuration.
		/// </summary>
		/// <param name="configurationName">Configuration name to set.</param>
		void SetConfigurationName(string configurationName);
	}
}
